<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>qspips: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">qspips
   </div>
   <div id="projectbrief">Vitis Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="pages.html"><span>Examples</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">qspips Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This file contains the implementation of the <a class="el" href="struct_x_qspi_ps.html" title="The XQspiPs driver instance data. ">XQspiPs</a> driver. It supports only master mode. User documentation for the driver functions is contained in this file in the form of comment blocks at the front of each function.</p>
<p>A QSPI device connects to an QSPI bus through a 4-wire serial interface. The QSPI bus is a full-duplex, synchronous bus that facilitates communication between one master and one slave. The device is always full-duplex, which means that for every byte sent, one is received, and vice-versa. The master controls the clock, so it can regulate when it wants to send or receive data. The slave is under control of the master, it must respond quickly since it has no control of the clock and must send/receive data as fast or as slow as the master does.</p>
<p><b> Linear Mode </b> The Linear Quad-SPI Controller extends the existing Quad-SPI Controller�s functionality by adding a linear addressing scheme that allows the SPI flash memory subsystem to behave like a typical ROM device. The new feature hides the normal SPI protocol from a master reading from the SPI flash memory. The feature improves both the user friendliness and the overall read memory throughput over that of the current Quad-SPI Controller by lessening the amount of software overheads required and by the use of the faster AXI interface.</p>
<p><b>Initialization &amp; Configuration</b></p>
<p>The <a class="el" href="struct_x_qspi_ps___config.html" title="This typedef contains configuration information for the device. ">XQspiPs_Config</a> structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.</p>
<p>To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized in the following way:</p>
<ul>
<li>XQspiPs_LookupConfig(DeviceId) - Use the device identifier to find static configuration structure defined in <a class="el" href="xqspips__g_8c.html">xqspips_g.c</a>. This is setup by the tools. For some operating systems the config structure will be initialized by the software and this call is not needed.</li>
<li>XQspiPs_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure.</li>
</ul>
<p><b>Multiple Masters</b></p>
<p>More than one master can exist, but arbitration is the responsibility of the higher layer software. The device driver does not perform any type of arbitration.</p>
<p><b>Modes of Operation</b></p>
<p>There are four modes to perform a data transfer and the selection of a mode is based on Chip Select(CS) and Start. These two options individually, can be controlled either by software(Manual) or hardware(Auto).</p>
<ul>
<li>Auto CS: Chip select is automatically asserted as soon as the first word is written into the TXFIFO and de asserted when the TXFIFO becomes empty</li>
<li>Manual CS: Software must assert and de assert CS.</li>
<li>Auto Start: Data transmission starts as soon as there is data in the TXFIFO and stalls when the TXFIFO is empty</li>
<li>Manual Start: Software must start data transmission at the beginning of the transaction or whenever the TXFIFO has become empty</li>
</ul>
<p>The preferred combination is Manual CS and Auto Start. In this combination, the software asserts CS before loading any data into TXFIFO. In Auto Start mode, whenever data is in TXFIFO, controller sends it out until TXFIFO becomes empty. The software reads the RXFIFO whenever the data is available. If no further data, software disables CS.</p>
<p>Risks/challenges of other combinations:</p>
<ul>
<li>Manual CS and Manual Start: Manual Start bit should be set after each TXFIFO write otherwise there could be a race condition where the TXFIFO becomes empty before the new word is written. In that case the transmission stops.</li>
<li>Auto CS with Manual or Auto Start: It is very difficult for software to keep the TXFIFO filled. Whenever the TXFIFO runs empty, CS is de asserted. This results in a single transaction to be split into multiple pieces each with its own chip select. This will result in garbage data to be sent.</li>
</ul>
<p><b>Interrupts</b></p>
<p>The user must connect the interrupt handler of the driver, XQspiPs_InterruptHandler, to an interrupt system such that it will be called when an interrupt occurs. This function does not save and restore the processor context such that the user must provide this processing.</p>
<p>The driver handles the following interrupts:</p>
<ul>
<li>Data Transmit Register/FIFO Underflow</li>
<li>Data Receive Register/FIFO Not Empty</li>
<li>Data Transmit Register/FIFO Overwater</li>
<li>Data Receive Register/FIFO Overrun</li>
</ul>
<p>The Data Transmit Register/FIFO Overwater interrupt &ndash; indicates that the QSPI device has transmitted the data available to transmit, and now its data register and FIFO is ready to accept more data. The driver uses this interrupt to indicate progress while sending data. The driver may have more data to send, in which case the data transmit register and FIFO is filled for subsequent transmission. When this interrupt arrives and all the data has been sent, the driver invokes the status callback with a value of XST_SPI_TRANSFER_DONE to inform the upper layer software that all data has been sent.</p>
<p>The Data Transmit Register/FIFO Underflow interrupt &ndash; indicates that, as slave, the QSPI device was required to transmit but there was no data available to transmit in the transmit register (or FIFO). This may not be an error if the master is not expecting data. But in the case where the master is expecting data, this serves as a notification of such a condition. The driver reports this condition to the upper layer software through the status handler.</p>
<p>The Data Receive Register/FIFO Overrun interrupt &ndash; indicates that the QSPI device received data and subsequently dropped the data because the data receive register and FIFO was full. The driver reports this condition to the upper layer software through the status handler. This likely indicates a problem with the higher layer protocol, or a problem with the slave performance.</p>
<p><b>Polled Operation</b></p>
<p>Transfer in polled mode is supported through a separate interface function <a class="el" href="group__qspips.html#ga92bcb2ff87e82a4f27e9a49db023d08d" title="Transfers specified data on the QSPI bus in polled mode. ">XQspiPs_PolledTransfer()</a>. Unlike the transfer function in the interrupt mode, this function blocks until all data has been sent/received.</p>
<p><b>Device Busy</b></p>
<p>Some operations are disallowed when the device is busy. The driver tracks whether a device is busy. The device is considered busy when a data transfer request is outstanding, and is considered not busy only when that transfer completes (or is aborted with a mode fault error).</p>
<p><b>Device Configuration</b></p>
<p>The device can be configured in various ways during the FPGA implementation process. Configuration parameters are stored in the <a class="el" href="xqspips__g_8c.html">xqspips_g.c</a> file or passed in via <a class="el" href="group__qspips.html#gaf348b6ee07c1e3e7d01857a789e658d4" title="Initializes a specific XQspiPs instance such that the driver is ready to use. ">XQspiPs_CfgInitialize()</a>. A table is defined where each entry contains configuration information for an QSPI device, including the base address for the device.</p>
<p><b>RTOS Independence</b></p>
<p>This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.</p>
<p>NOTE: This driver was always tested with endianness set to little-endian.</p>
<pre>
 MODIFICATION HISTORY:</pre><pre> Ver   Who Date     Changes
</p>
<hr/>
<p>
 1.00a sdm 11/25/10 First release, based on the PS SPI driver...
 1.01a sdm 11/22/11 Added TCL file for generating QSPI parameters
                     in xparameters.h
 2.00a kka 07/25/12 Added a few register defines for CR 670297
                     Removed code related to mode fault for CR 671468
                     The XQspiPs_SetSlaveSelect has been modified to remove
                     the argument of the slave select as the QSPI controller
                     only supports one slave.
                     XQspiPs_GetSlaveSelect API has been removed
                     Added a flag ShiftReadData to the instance structure
.                    and is used in the XQspiPs_GetReadData API.
                     The ShiftReadData Flag indicates whether the data
                     read from the Rx FIFO needs to be shifted
                     in cases where the data is less than 4  bytes
                     Removed the selection for the following options:
                     Master mode (XQSPIPS_MASTER_OPTION) and
                     Flash interface mode (XQSPIPS_FLASH_MODE_OPTION) option
                     as the QSPI driver supports the Master mode
                     and Flash Interface mode and doesnot support
                     Slave mode or the legacy mode.
                     Modified the XQspiPs_PolledTransfer and XQspiPs_Transfer
                     APIs so that the last argument (IsInst) specifying whether
                     it is instruction or data has been removed. The first byte
                     in the SendBufPtr argument of these APIs specify the
                     instruction to be sent to the Flash Device.
                     This version of the driver fixes CRs 670197/663787/
                     670297/671468.
                     Added the option for setting the Holdb_dr bit in the
                     configuration options, XQSPIPS_HOLD_B_DRIVE_OPTION
                     is the option to be used for setting this bit in the
                     configuration register.
                     The XQspiPs_PolledTransfer function has been updated
                     to fill the data to fifo depth.
 2.01a sg  02/03/13 Added flash opcodes for DUAL_IO_READ,QUAD_IO_READ.
                     Added macros for Set/Get Rx Watermark. Changed QSPI
                     Enable/Disable macro argument from BaseAddress to
                     Instance Pointer. Added DelayNss argument to SetDelays
                     and GetDelays API's.
                     Created macros XQspiPs_IsManualStart and
                     XQspiPs_IsManualChipSelect.
                     Changed QSPI transfer logic for polled and interrupt
                     modes to be based on filled tx fifo count and receive
                     based on it. RXNEMPTY interrupt is not used.
                     Added assertions to XQspiPs_LqspiRead function.
                     SetDelays and GetDelays API's include DelayNss parameter.
                     Added defines for DelayNss,Rx Watermark,Interrupts
                     which need write to clear. Removed Read zeros mask from
                     LQSPI Config register. Renamed Fixed burst error to
                     data FSM error in  LQSPI Status register.</pre><pre> 2.02a hk  05/07/13 Added ConnectionMode to config structure.
                         Corresponds to C_QSPI_MODE - 0:Single, 1:Stacked, 2:Parallel
                         Added enable and disable to the <a class="el" href="group__qspips.html#gacbdefc29998bb7b4a61e62f8ef3ed127" title="Read the flash in Linear QSPI mode. ">XQspiPs_LqspiRead()</a> function
                         Removed XQspi_Reset() in Set_Options() function when
                         LQSPI_MODE_OPTION is set.
            Added instructions for bank selection, die erase and
            flag status register to the flash instruction table
            Handling for instructions not in flash instruction
                         table added. Checking for Tx FIFO empty when switching from
                         TXD1/2/3 to TXD0 added. If WRSR instruction is sent with
            byte count 3 (spansion), instruction size and TXD register
                         changed accordingly. CR# 712502 and 703869.
            Added prefix to constant definitions for ConnectionMode
            Added (#ifdef linear base address) in the Linear read function.
            Changed  XPAR_XQSPIPS_0_LINEAR_BASEADDR to
            XPAR_PS7_QSPI_LINEAR_0_S_AXI_BASEADDR in
            XQspiPs_LqspiRead function. Fix for CR#718141.</pre><pre> 2.03a hk  09/17/13 Modified polled and interrupt transfers to make use of
                    thresholds. This is to improve performance.
                    Added API's for QSPI reset and
                    linear mode initialization for boot.
                    Added RX and TX threshold reset to one in XQspiPs_Abort.
                    Added RX threshold reset(1) after transfer in polled and
                    interrupt transfers. Made changes to make sure threshold
                    change is done only when no transfer is in progress.
                    Updated linear init API for parallel and stacked modes.
                    CR#737760.
 3.1   hk  08/13/14 When writing to the configuration register, set/reset
                    required bits leaving reserved bits untouched. CR# 796813.
 3.2    sk      02/05/15 Add SLCR reset in abort function as a workaround because
                                         controller does not update FIFO status flags as expected
                                         when thresholds are used.
 3.3   sk  11/07/15 Modified the API prototypes according to MISRAC standards
                    to remove compilation warnings. CR# 868893.
       ms  03/17/17 Added readme.txt file in examples folder for doxygen
                    generation.
       ms  04/05/17 Modified Comment lines in functions of qspips
                    examples to recognize it as documentation block
                    and modified filename tag in
                    <a class="el" href="xqspips__dual__flash__stack__lqspi__example_8c.html" title="This file contains a design example using the QSPI driver (XQspiPs) in Linear QSPI mode...">xqspips_dual_flash_stack_lqspi_example.c</a> to include it in
                    doxygen examples.
 3.4   nsk 31/07/17 Added QSPI_BUS_WIDTH parameter in xparameters.h file
 3.5    tjs 08/21/18 Fixed compilation warnings for the ARMCC.
 3.5    tjs 07/16/18 Added support for low density ISSI flash parts.
 3.6   akm 03/28/19 Fixed memory leak issue while reading from qspi.(CR#1016357)
 3.6   akm 04/15/19 Modified FlashQuadEnable, FlashWrie and FlashErase APIs,
                    to wait for the on going operation to complete before
                    performing the next operation.
 3.6   akm 04/15/19 Modified the mask in XQspiPs_GetReadData() API to retrieve
                    configuration register values of both the Flashes in dual
                    parellel connection.
 3.7    akm 11/19/19 Fixed Coverity unused value warning in <a class="el" href="group__qspips.html#ga92bcb2ff87e82a4f27e9a49db023d08d" title="Transfers specified data on the QSPI bus in polled mode. ">XQspiPs_PolledTransfer()</a>
                        and <a class="el" href="group__qspips.html#gaeafbee8d795ef8805ab7c8756f5e2274" title="Transfers specified data on the QSPI bus. ">XQspiPs_Transfer()</a> APIs.
 3.7    akm 03/19/20 Modified <a class="el" href="group__qspips.html#ga92bcb2ff87e82a4f27e9a49db023d08d" title="Transfers specified data on the QSPI bus in polled mode. ">XQspiPs_PolledTransfer()</a>, <a class="el" href="group__qspips.html#gaeafbee8d795ef8805ab7c8756f5e2274" title="Transfers specified data on the QSPI bus. ">XQspiPs_Transfer()</a> and
                        <a class="el" href="group__qspips.html#ga44c9e0841d774e9c4958e2cdd8c23220" title="The interrupt handler for QSPI interrupts. ">XQspiPs_InterruptHandler()</a> APIs to fill TX FIFO with valid
                        data when RX buffer is not NULL.
 3.8    akm 09/02/20 Updated the Makefile to support parallel make execution.
 3.11   akm 07/10/23 Update the driver to support for system device-tree flow.
 3.12   sb  02/20/24 Add missing parenthesis for macro expansions.</pre><pre> </pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
	<p class="footer">&copy; Copyright 2015-2022 Xilinx, Inc. All Rights Reserved.</p>
	<p class="footer">&copy; Copyright 2022-2023 Advanced Micro Devices, Inc. All Rights Reserved.</p>
</div>
</body>
</html>
